Using the XMLDoc tool for API documentation with Borland Developer Studio 2006

This document describes how to use the XMLDoc demo project to generate documentation from XML comments in Delphi and C# code. For Delphi code, the XMLDoc tool reads the xml file generated by the Delphi compiler's --doc switch. For C#, the tool combines the output from the C# compiler's /doc switch with metadata from reflection. Source code comments that use a special syntax are inserted into HTML files identical to those used for the Developer Studio 2006 product API documentation. These files can be viewed with any HTML browser. Links are in the Microsoft Help 2.0 format, so they will not function as-is. For full functionality, the files can be compiled into the Microsoft Help 2.0 compiled help format using the Borland HelpKit and the Visual Studio Help Integration Kit.

Requirements

The XMLDoc tool requires a number of supporting tools:

• Developer Studio 2006 or later
• Python (tested with Python 2.4)
• Saxon (tested with Saxon 6.5.3, full version)
• The Java SDK (tested with J2SE v 1.5.0_04 SDK)

Setup

To prepare to use the XMLDoc tool, add the directory containing the tool to your path. In the default installation, this path is C:\Program Files\Borland\BDS\4.0\Demos\XMLDoc. Consult your operating system documentation for instructions on changing your path environment variable.

You should also add the directory containing Python to your path if it is not already there. Because the XMLDoc tool executes saxon from the command line, if you use the full version of Saxon you will need to use a batch file to start Saxon. The batch file should be called saxon.bat, and should look something like this (change the path to match your local Saxon installation):

@java -jar "C:\Program Files\Saxon 6.5.3\saxon.jar" %1 %2 %3

Place this batch file in your path.

Basic usage

There are three major tasks you need to perform to produce XML documentation from source code comments:

1. Use the Delphi or C# compiler to generate the XML file with source code comments
2. Use the XMLDoc tool to produce HTML files in the format used by Microsoft Help 2.0
3. Use the Visual Studio Help Integration Kit and the Borland HelpKit to compile and install the new help topics

Each of these steps is broken into subtasks below.

Using the Delphi or C# compiler to generate the XML file with source code comments

1. Write comments describing your classes, types, and members in the declaration section of your code.

   For your comments to appear in the output, you must use one of the special XML documentation comment marker styles:

   /// This comment goes until the end of the line -- works in Delphi and C#
   {! This is also a comment -- works only in Delphi }
   {*! and this too -- works only in Delphi *}
   

   The relevant documentation should appear directly above the declaration of the documented type or member. For example:

   [Delphi]
   /// The TFooBar class includes an extremely useful method.
   type TFooBar = class(System.Windows.Forms.Form);
   	public
   		/// The method FooMethod is extremely useful.
   		function FooMethod: Integer;
   end;
   

   [C#]
   /// The FooBar class includes an extremely useful method.
   class FooBar : System.Windows.Forms.Form
   {
   	/// The method FooMethod is extremely useful.
   	public int FooMethod();
   }
   

   Note: Private members may not be processed by the XMLDoc tool.

2. Enable the --doc or /doc switch in the IDE, by clicking the checkbox for the Generate XML documentation option on the ProjectOptions...Compiler page.
3. Compile and build your project.

Using the XMLDoc tool to produce HTML files in the format used by Microsoft Help 2.0

1. Using any text editor or an XML editor, customize the variables in vars.xml. This file is located in the xmldoc/xml subdirectory of the folder where the xmldoc.py file is located. vars.xml contains text strings that are inserted into the output HTML in various places. You will certainly want to change the text in the <copyrightMessage> node, and you may wish to customize other text strings as well.
2. Open a command prompt.
3. Type xmldoc.py <MyProjectDir>, where <MyProjectDir> is the project directory for the project you are documenting. By default this will be something like xmldoc.py "C:\Documents and Settings\UserName\My Documents\Borland Studio Projects\Project1". Don't forget the quotes if your project directory name has spaces in it.
4. Go to the newly created doc subdirectory of your project directory, and examine the output HTML files in doc/final.

Using the Visual Studio Help Integration Kit and the Borland HelpKit to compile and install the new help topics

1. Compile into H20 files (.HxS and .HxI files) using the Visual Studio Help Integration Kit (VSHIK). Though you can view your HTML files as-is, this step is required to have your HTML files function as Help 2.0 files. The VSHIK is available as a free download from Microsoft. The use of that tool is beyond the scope of this document; see the documentation from Microsoft and from third parties like The Helpware Group for instructions.
2. Create an installer to integrate your help files into the Developer Studio 2006 IDE using the Borland HelpKit. This step is required if you wish to redistribute your help files and have them integrate with the Developer Studio 2006 IDE. The HelpKit is available as a free download on the Borland Developer Network website. Follow the instructions provided with the HelpKit.

Advanced usage

The XMLDoc tool is very flexible. You can use source files outside of your code if desired. Also, by customizing stylesheets, you can produce documentation with whatever appearance or structure you desire.

Maintaining content outside of code

Customizing look-and-feel

Customizing structure